How to use the video recorder utility

The Video recorder utility is used to record video clips to files, descriptors or URLs and manipulate embedded meta data. This functionality is implemented by the CVideoRecorderUtility class.

The sequence diagram below explains the different functionalities of the Video Recorder Utility:

Using a video recorder utility involves the following tasks:

• Construct utility object and open recording device

• Configure video recording parameters

• Record and related functions

• Metadata

• Plug-in control

The MMF (MultiMedia Framework) provides a simple interface to the application level API called CVideoRecorderUtility. Using this interface, you can record a video clip and set meta data and control information for it. The resultant video clip can be saved to a file, descriptor, or URL. You can create an object of this utility class using the CVideoRecorderUtility::NewL function. Some video formats also allow storing of audio data. To facilitate this feature, the class contains audio functions that can manipulate audio data.

void CRecordVideo::ConstructL()
    {
    iVideoRecordUtility = CVideoRecorderUtility::NewL(*this);
    }

Certain parameters like, the handle to the camera, the controller UID, video format and the codecs to use for video and audio need to be specified for recording. This is shown in the range of open statements shown below based on where you want to save the video clip:

• CVideoRecorderUtility::OpenFileL: This function stores the recorded video clip in a file.

  void OpenFileL(const TDesC& aFileName, TInt aCameraHandle, TUid aControllerUid, 
TUid aVideoFormat, TFourCC aVideoType=KFourCCNULL, TFourCC aAudioType=KFourCCNULL);

  Note: There is also another method to save a video clip to a file. It is strongly recommended to use this method.

  OpenFileL(const TMMSource& aSource, TUid aControllerUid);

  Where aSource is a filename or an open handle to a file where the video clip has to be saved and aControllerUid is an optionally specified plugin. If specified, it will force the video player to use the controller with the given UID. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached.

• CVideoRecorderUtility::OpenDesL: This function stores the recorded video clip in a descriptor.

  void OpenDesL(TDes8& aDescriptor, TInt aCameraHandle, TUid aControllerUid, 
TUid aVideoFormat,TFourCC aVideoType=KFourCCNULL, TFourCC aAudioType=KFourCCNULL);

• CVideoRecorderUtility::OpenUrlL: This function stores the recorded video clip in a URL.

  void OpenUrlL(const TDesC& aUrl, TInt aIapId = KUseDefaultIap, TInt aCameraHandle, TUid
 aControllerUid, TUid aVideoFormat, TFourCC aVideoType=KFourCCNULL, TFourCC aAudioType=KFourCCNULL);

Once the camera is ready and the video clip is opened successfully, call the CVideoRecorderUtility::Prepare() function. This function prepares the record controller for use. When the preparation of the record controller is complete, successfully or otherwise, a callback function MVideoRecorderUtilityObserver::MvruoPrepareComplete is called to notify that the video recorder is ready to record.

General

This category details various functions used to set and report playback priorities in relation to other applications that are trying to use audio/video resources. Use the following functions to detect or set audio tracks within video clips and also report and set video frame sizes:

• To set the priority of the video/audio device, which is used to arbitrate between multiple objects trying to access a controller, use the CVideoRecorderUtility::SetPriorityL() function.

  void CRecordVideo::SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref)
    {
    iVideoRecordUtility->SetPriorityL(aPriority, aPref);
    }

  To retrieve the priority setting of the video/audio device, use the CVideoRecorderUtility::GetPriorityL() function.

  void CRecordVideo::GetPriorityL(TInt &aPriority, TMdaPriorityPreference &aPref)
    {
    iVideoRecordUtility->GetPriorityL(aPriority, aPref);
    }

• To determine whether an audio track is associated with a video clip, use the CVideoRecorderUtility::AudioEnabledL(). This function returns the status of audio support for the video clip currently being recorded.

   TBool CRecordVideo::AudioEnabledL()
    {
    return iVideoRecordUtility->AudioEnabledL();
    }
    

  To set whether the current video clip has an audio track associated with it, use clipCVideoRecorderUtility::SetAudioEnabledL() function.

   void CRecordVideo::SetAudioEnabledL(TBool aEnabled)
    {
    iVideoRecordUtility->SetAudioEnabledL(aEnabled);
    }

  Note: The above listed APIs are relevant only if the video clip is associated with an audio stream.

• To retrieve the current frame size of the video clip, use the CVideoRecorderUtility::GetVideoFrameSizeL().This function returns the video frame size in pixels.

   void CRecordVideo::GetVideoFrameSizeL(TSize &aSize)
    {
    iVideoRecordUtility->GetVideoFrameSizeL(aSize);
    }

  To set the video frame to the desired size, use CVideoRecorderUtility::SetVideoFrameSizeL() function. This functions sets the video frame size in pixels.

   void CRecordVideo::SetVideoFrameSizeL(const TSize &aSize)
    {
    iVideoRecordUtility->SetVideoFrameSizeL(aSize);
    }

  To set the video frame size to 176x144, use the CVideoRecorderUtility::SetVideoFrameSizeL() function.

   TSize frameSize;
    frameSize.iWidth = 176;
    frameSize.iHeight = 144;
    TRAP(err, iVideoRecorderUtility->SetVideoFrameSizeL(frameSize));

MIME type and Codecs

This sections covers the reporting and setting of formats and codecs for video and audio data. You can use the following functions to report and set video and audio codecs.

• To retrieve a list of video codecs supported by the currently open video clip, use CVideoRecorderUtility::GetSupportedVideoTypesL()function. This function returns an array of Four Character Codes representing the video types supported.

  To retrieve a list of audio codecs supported by the current video clip, use CVideoRecorderUtility::GetSupportedAudioTypesL()function. This function returns an array of Four Character Codes representing the audio types supported.

• To retrieve an audio codec currently in use by the video clip, use the and CVideoRecorderUtility::AudioTypeL() function. This function returns the audio type of the clip.

  TFourCC CRecordVideo::AudioTypeL()
    {
    return iVideoRecordUtility->AudioTypeL();
    }

• To set new video and audio codecs to use when recording data to the video clip, use the CVideoRecorderUtility::SetVideoTypeL() and CVideoRecorderUtility::SetAudioTypeL() functions.

  void CRecordVideo::SetVideoTypeL(const TDesC8 &aType)
    {
    iVideoRecordUtility->SetVideoTypeL(aType);
    }

   void CRecordVideo::SetAudioTypeL(TFourCC aType)
    {
    iVideoRecordUtility->SetAudioTypeL(aType);
    }

Bit and frame rates

You can use the following functions to report the bit and frame rate settings for video clips and associated audio tracks.

• To retrieve or set the video bit rates, use the CVideoRecorderUtility::VideoBitRateL() and CVideoRecorderUtility::SetVideoBitRateL() functions.

  TInt CRecordVideo::VideoBitRateL()
    {
    return iVideoRecordUtility->VideoBitRateL();
    }

   void CRecordVideo::SetVideoBitRateL(TInt aBitRate)
    {
    iVideoRecordUtility->SetVideoBitRateL(aBitRate);
    }

• To retrieve or set the audio bit rates, use the CVideoRecorderUtility::AudioBitRateL() and CVideoRecorderUtility::SetAudioBitRateL() functions.

  TInt CRecordVideo::AudioBitRateL()
    {
    return iVideoRecordUtility->AudioBitRateL();
    }

   void CRecordVideo::SetAudioBitRateL(TInt aBitRate)
    {
    iVideoRecordUtility->SetAudioBitRateL(aBitRate);
    }

• To retrieve or set the current frame rate of the video, use the CVideoRecorderUtility::VideoFrameRateL() and CVideoRecorderUtility::SetVideoFrameRateL() functions.

   TReal32 CRecordVideo::VideoFrameRateL()
    {
    return iVideoRecordUtility->VideoFrameRateL();
    }

  void CRecordVideo::SetVideoFrameRateL(TReal32 aFrameRate)
    {
    iVideoRecordUtility->SetVideoFrameRateL(aFrameRate);
    }

Gain

The functions for controlling gain settings for recording devices are CVideoRecorderUtility::GainL(), CVideoRecorderUtility::SetGainL() and CVideoRecorderUtility::MaxGainL(). GainL() returns the current recording gain. SetGainL() sets the audio recording gain. MaxGain() returns the maximum possible setting for the recording gain.

 TInt CRecordVideo::GainL() 
    {
    return iVideoRecordUtility->GainL();
    }

void CRecordVideo::SetGainL(TInt aGain)
    {
    iVideoRecordUtility->SetGainL(aGain);
    }

TInt CRecordVideo::MaxGainL() 
    {
    return iVideoRecordUtility->MaxGainL();
    }

If you are using an audio clip, the recording gain must be set using the CVideoRecorderUtility::SetGainL() function before recording because the initial gain is undefined or may also have been modified by another client application. The specific functions to record and perform related tasks are as follows:

• To start recording video data to the specified file, descriptor or URL, use the CVideoRecorderUtility::Record() function.

  void CRecordVideo::Record()
    {
    iVideoRecordUtility->Record();
    }

• To pause recording, use the CVideoRecorderUtility::PauseL() function. The position within the video clip is maintained in case a subsequent CVideoRecorderUtility::RecordL() is called.

  void CRecordVideo::PauseL()
    {
    iVideoRecordUtility->PauseL();
    }

• To stop recording, use the CVideoRecorderUtility::Stop() function. If the video format supports audio tracks and if audio is enabled, this function also stops recording the audio data.

  TInt CRecordVideo::Stop()
    {
    TInt err = iVideoRecordUtility->Stop();
    return err;
    }

• To close all related video and audio controllers, use the CVideoRecorderUtility::Close() function.

  void  CRecordVideo::Close()
    {
    iVideoRecordUtility->Close();
    }

To set various metadata entries, use the CVideoRecorderUtility::AddMetaDataEntryL() function. The metadata entries are stored within the clip itself and can be retrieved or modified anytime during the recording.This is usually used to store information such as copyright information, creator, creation date and so on.

To retrieve specific metadata entries from a video clip, use the CVideoRecorderUtility::MetaDataEntryL() function.

The following code adds the copyright information to the video clip:

// Create Meta Entries
_LIT(name,"<Copyright>");
_LIT(data,"<Symbian ©) 2002>");
CMMFMetaDataEntry* metaData = NULL;
metaData = CMMFMetaDataEntry::NewL(name,data);
CleanupStack::PushL(metaData);
// Add the meta data entry
TRAP(err, iVideoRecorderUtility->AddMetaDataEntryL(*metaData));

Custom commands

Custom commands are used to pass the message directly to the controller plug-in instead of going through APIs such as Play(), Record(), and so on.

To send a synchronous custom command to the controller, use the CustomCommandSync() function.

To send a asynchronous custom command to the controller, use the CustomCommandAsync() function.